<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>PyGUI - Event Handling</title>
  
                                   <meta name="GENERATOR" content="Mozilla/3.01Gold (X11; I; SunOS 5.6 sun4u) [Netscape]"></head>
<body>
       <h1>Event Handling</h1>
       <p>This section describes how the various types of events are handled, and
  how the Application, Document, Window and View classes interact when handling
  events.</p>
       <p>Events can be classified into three groups:</p>
       <ol>
     <li>Mouse events</li>
      <li>Keyboard events</li>
      <li>Menu commands</li>
      </ol>
       <p>Although menu commands are not explicitly represented as Event objects, 
  they are handled in a similar way to events.</p>
       <h2>Mouse events</h2>
       <p>There are four kinds of mouse events, <i>mouse-down</i>, <i>mouse-drag</i>, <i>mouse-up&nbsp;</i>and <span style="font-style: italic;">mouse_move.</span>
    </p>
    <p>Mouse-down
and mouse-up events occur when a mouse button is pressed or released.
Mouse-drag events occur when the mouse is moved with a button held
down. Mouse-move events occur when the mouse is moved with no button down.<br>
</p>
<p>Mouse events are delivered simply by calling the
correspondingly-named method, if any, of the View object with which
they are associated. For example, mouse-down events are delivered by
calling the <tt>mouse_down</tt>
method of the view in which it occurs. If that view does not define a method with that name, the event is ignored.<br>
</p>
<p>Note that mouse-drag and mouse-up events are sent to the view in
which the preceding mouse-down event occurred, not the one currently
containing the mouse.<br>
</p>

       <p>There is also an alternative way of receiving mouse-drag and mouse-up events, by entering a modal <i>mouse-tracking loop</i> in response
  to a mouse-down event (see <a href="using_the_view_class.html#Mouse_tracking">Mouse Tracking</a>).</p><span style="font-style: italic;"></span><h2>Message delivery mechanism</h2>
       <p>Keyboard events and menu commands are handled by a general mechanism called
  the <i>message delivery mechanism. </i>A <i>message</i> consists of a message 
  name and optionally a tuple of arguments. The objects which can respond 
to messages are subclasses of MessageHandler, and are arranged in a hierarchy 
  which corresponds partly to the Component containment hierarchy.</p>
       <p>Message delivery proceeds in two phases, the <i>dispatching phase </i>and 
  the <i>handling phase</i>. <br>
  </p>
  <p>At any given moment, one of the application's windows is the <i>target
 window</i> for keboard events and menu commands. Depending on the platform,
 this may be the frontmost window,  or the window containing the mouse pointer,
 or it may be determined in some other way. Within the target window, one
of the components is designated as the <i>target object</i>, or just <i>target</i>.
 The user typically makes a component the target by clicking on it or tabbing
 into it. A component can also be made the target by calling its <tt>become_target</tt>
method.<br>
  </p>
  <p>If no component has been selected as the target within a window, the target
 defaults to the window itself. If the application has no windows (possible
 on some platforms), the Application is the target.<br>
  </p>
  <p>The dispatching phase consists of locating the target object and passing
 the message to it. The handling phase is then entered by calling the <tt>handle</tt>
method  of the target. If the target has a method called <tt>xxx</tt>, where
 <i>xxx  </i>is the name of the message, it is called with the message arguments. 
 Otherwise, the message is passed to the <tt>handle</tt> method of the object's 
 <i>next handler</i>. In the case of a Component, the next handler is the 
component's container. </p>
       <p>When the message reaches a Window object, it passes to the Document object
  which owns the Window, and then to the Application object. If the Window
 is not owned by a Document, the message is passed directly to the Application.</p>
       <h2>Keyboard events</h2>
       <p>Keyboard events may be classified into <i>key-down</i>, <i>key-up</i> and
<i>auto-key</i> events.<br>
   </p>
       <p>Key-down events are processed by dispatching a message named <tt>key</tt>_<tt>down</tt>, 
  with the event as its argument, to the current target. <br>
   </p>
   <p>Key-up events are not supported by all platforms. Where they are supported, 
 they are handled by dispatching a <tt>key_up</tt> message to the current
 target.<br>
   </p>
   <p>An auto-key event is a key-down event generated by an auto-repeating key 
 rather than a physical keystroke, and is also handled by dispatching a <tt>key_down</tt> message. Not all platforms allow auto-key events to be distinguished from 
 key-down events; on platforms which do, they are distinguished by the <tt>auto</tt>
attribute of the event object being set to true.<br>
   </p>
       <h2>Menu commands</h2>
       <p>The binding between a menu item and the action it invokes is through an
  internal<i> command name</i> associated with the menu item. This allows
menu items to be rearranged and their text altered without affecting the
code of objects which handle the commands. Furthermore, the method to invoke
in response to a menu command is located by sending messages along the same 
 paths that keyboard events follow. This allows the same menu item to have 
 different effects depending on the context in which it is used.</p>
       <p>There are two phases to handling menu commands, the <i>setup phase</i>  and the <i>execution phase</i>. Each of these phases involves sending messages 
  up the message handler hierarchy.</p>
       <p>The purpose of the setup phase is to set up the menus so that the appropriate 
  subset of the commands are enabled, and any check marks or other visual 
indications are in an appropriate state.</p>
       <p>Before pulling down the menu, all items in all menus of the current menubar
  are first disabled (and any check marks, etc. are removed). Then the <tt>setup_menus</tt>
method of each object along the next-handler chain from the current target
  is called. In response to this, each object enables those menu commands
which  it knows about and are currently legal (and sets up any necessary
check marks,  etc.)</p>
       <p>Then the menu is pulled down and the user allowed to make a selection. 
  If a selection is made, a message is dispatched whose name is the command 
  name of the selected item. </p>
      As well as a single menu item, a command name can also be associated
 with a <i>group</i> of menu items whose contents can vary at run time. Examples 
 might be a list of font names in a Font menu, or a list of window titles 
in a Windows menu. Within the group, individual items are distinguished by 
an integer index. When an item from the list is invoked, its index is passed 
 as a parameter of the command message.<br>
    <br>
  <br>
 <br>
</body></html>